home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_100 / 120_01 / l2.doc < prev    next >
Text File  |  1985-03-09  |  15KB  |  532 lines
  1.  
  2.  
  3.  
  4. L2 (C Linker) v2.1               1                         7 Dec 81
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.                    The Mark of the Unicorn Linker
  16.                              For BDS C
  17.  
  18.                            v2.1 7 Dec 81
  19.                          Linker and Docs by
  20.                 Scott W. Layson, Mark of the Unicorn
  21.  
  22.  
  23. L2 is an  alternative  to  CLINK  for  linking  BDS  C programs.  A
  24. program linked with CLINK will  have  a jump table at the beginning
  25. of  each function; calls to other  functions  are  made  indirectly
  26. through  the  table.  L2 eliminates these jump tables, and  adjusts
  27. indirect calls through them to go directly to the target function. 
  28. Besides  making the code imperceptibly faster, this  has  two  real
  29. advantages: one, it makes the code smaller by 4% to 10% (the latter
  30. has  been  observed  in  a  program containing many small functions
  31. which do  little besides call a few other functions), and it allows
  32. SID  to  display the  name  of  the  target  function  of  a  call,
  33. simplifying debugging. 
  34.  
  35. L2  seems  to  be complete enough to replace CLINK  entirely.   Its
  36. biggest  advantage is that it's written in C, so that if  you  need
  37. some feature  it  doesn't  have, you can just hack it in.  However,
  38. its  user  interface and certain aspects of its behavior are rather
  39. different. 
  40.  
  41. The most important difference  is  the distinction it makes between
  42. "program" and  "library"  CRL  files.   Program files are loaded in
  43. their  entirety;  each  function  in a program file is  linked  in,
  44. whether or not it has been referenced by the time it is encountered
  45. (unless another function  with  the  same  name  has  already  been
  46. loaded).  Library files  are  scanned  for  needed  functions; only
  47. those that have been referenced by another function are included in
  48. the  object code.  CLINK treats all CRL files as libraries in  this
  49. sense (except see the -f option for v1.4). 
  50.  
  51. A typical command line is
  52.  
  53.      l2 foo bar -l bletch grotz -wa
  54.  
  55. Given this command, L2 will load all the  functions  in FOO.CRL and
  56. BAR.CRL  (the  program files).  Then it  will  scan  the  libraries
  57. BLETCH.CRL, GROTZ.CRL, DEFF.CRL,  and DEFF2.CRL (in that order) for
  58. functions that have  been  referenced  but  not  linked.   If there
  59. remain unsatisfied references, L2 will display a list of the needed
  60. functions and  prompt  for  the name of a CRL file to scan; it will
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. L2 (C Linker) v2.1               2                         7 Dec 81
  71.  
  72.  
  73.  
  74.  
  75. repeat this process  until  all references are satisfied (just like
  76. CLINK). Then it will write the resulting code to  FOO.COM,  display
  77. the  link statistics, and write a symbol table (with the link stats
  78. appended) to FOO.SYM.
  79.  
  80. In more detail, then: here is a list of  the available command-line
  81. options.   Options  consist  of  a  dash  followed by  a  (possibly
  82. one-letter)  word,  preceded  and  followed  by  a  space.   Unlike
  83. CLINK's, L2's options  may  not  be combined; "-l -w", for example,
  84. may not be abbreviated "-lw"; and "-m fubar"  may  not  be  written
  85. "-mfubar".
  86.  
  87. -f <funcs>       Reserves enough table size for <funcs> functions. 
  88.                  (<funcs>  is  in decimal.)  The default is 200. If
  89.                  you  often  link  programs  with   more  than  200
  90.                  functions,  you  may wish to change the default --
  91.                  it's in setup() in L2.C.
  92.  
  93. -l                CRL file names  before  the  first  "-l"  on  the
  94.                  command line will be treated as program files; CRL
  95.                  files  after  the  first   "-l"   are  treated  as
  96.                  libraries.  Subsequent "-l"s have no effect. 
  97.  
  98. -m <name>        <name> becomes the  top-level  function.   This is
  99.                  the  function initially called when the .COM  file
  100.                  is run; by default,  of course, it is "main". Note
  101.                  that,  unlike  with  CLINK, the top-level function
  102.                  need not be the  first  function  in the first CRL
  103.                  file; it can be anywhere.  -m also works with -ovl
  104.                  (see below). 
  105.  
  106. -ovl <name> <addr>
  107.                  An overlay segment will be built instead of a root
  108.                  segment; the overlay will be linked to run at base
  109.                  address <addr> (entered in  hex).   <name>  is the
  110.                  name of  the root segment for which the overlay is
  111.                  being built; <name>.SYM, a symbol  table  produced
  112.                  with either L2 or CLINK,  will be read in *before*
  113.                  the CRL files,  to allow overlay functions to call
  114.                  root  functions.   The  name  of   the   top-level
  115.                  function in the overlay -- i.e., the one that gets
  116.                  invoked by a call to the overlay base  address  --
  117.                  is by  default  not "main", but rather <firstcrl>,
  118.                  the name of the first  CRL  file in the L2 command
  119.                  line.   The  overlay   segment   is   written   to
  120.                  <firstcrl>.OVL. (See example below.) 
  121.  
  122. -org <addr>      This option is used to produce a root segment with
  123.                  base address <addr>, e.g., for use  in  generating
  124.                  code for ROMming. <addr> is entered in hex, and is
  125.                  the starting address  of the code, not of RAM; the
  126.                  default is, of  course,  0x100. (To link a program
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. L2 (C Linker) v2.1               3                         7 Dec 81
  137.  
  138.  
  139.  
  140.  
  141.                  for   a   nonstandard  CP/M,  you  need  a  C.CCC,
  142.                  DEFF.CRL,  and DEFF2.CRL which have been assembled
  143.                  for that  address.   If  you  are  running L2 on a
  144.                  nonstandard  CP/M, you should change  the  default
  145.                  origin  in  setup()  to  0x4300.) If you are using
  146.                  this  option to generate code for ROM, be sure  to
  147.                  use the "-t" option also (see below). 
  148.  
  149. -t  <addr>         Works  just like the CLINK "-t" option: sets the
  150.                  stack pointer to the given address at the start of
  151.                  the run-time package.  This  option MUST ALWAYS BE
  152.                  USED when "-org" is used to generate code for ROM.
  153.                  IF   "-t"  is  NOT  used,  then  the   first   two
  154.                  instructions of the resulting COM file will be:
  155.  
  156.                       lhld origin-100h+6
  157.                       sphl
  158.  
  159.                  (where "origin" is normally 0x100 or 0x4300) while
  160.                  using  "-t" causes the first two  instructions  to
  161.                  be:
  162.  
  163.                       lxi sp,<addr>
  164.                       nop
  165.  
  166. -w                A  SID-compatible  symbol  table  is  written  to
  167.                  <firstcrl>.SYM,  where <firstcrl> is the  name  of
  168.                  the first CRL  file  listed  in the command line. 
  169.                  This table is normally produced in address  order,
  170.                  not alphabetical order like CLINK's; see below for
  171.                  how to change this. 
  172.  
  173. -wa              A variation on -w. The link statistics, which  are
  174.                  always  displayed on the console  at  the  end  of
  175.                  linking, are also appended to the .SYM  file.   If
  176.                  the resulting .SYM file is read into SID, SID will
  177.                  complain  by  issuing  its typical  verbose  error
  178.                  message "?", but then  will  work  correctly.  The
  179.                  big advantage of putting the stats at the  end  of
  180.                  the .SYM file is that one can subsequently look at
  181.                  that file to see exactly how long the code was and
  182.                  where the externals started. 
  183.  
  184. -ws              Another variation  on  -w.  This  one  writes  the
  185.                  symbol   table  to  <firstcrl>.SYM  and  the  link
  186.                  statistics to <firstcrl>.LNK.
  187.  
  188. Because L2 is so large, it cannot  always  link large programs in a
  189. single pass.  If it runs  out  of  memory  during  linking, it will
  190. switch automatically to (very slow) two-pass  mode.   (If